Configuration

This section provides information pertaining to configuration for Itential Ansible Manager.

Choose Inventory Mode

Before configuring Itential Ansible Manager, determine which inventory mode you require. For existing Ansible users, specify your inventory file in the inventory_file property to maintain all existing device variables and groups as used within your current Ansible® environment. Ansible Manager considers this mode external inventory. Conversely, internal inventory (i.e. an empty inventory_file property) allows manipulation of inventory information and management of your inventory (including management of inventory variables) via Ansible Manager.

One important factor to determine which mode to run Ansible Manager in depends on the desired mechanism for managing inventory:

• Internal - Management via Ansible Manager API.
• External - Management via file manipulation as with any Ansible installation.

Consider each approach, the inventory mode you desire, and choose accordingly.

Create Itential User and Group

As a best practice, assign each service to run as a specific user and group. The default user and group for the Ansible Manager service is itential.

Create the Itential user and group using the following command.

  sudo useradd -m -r -s /bin/false itential

Create Directory Structure and Properties.yml File

Use the following commands to create the directory structure and properties.yml file for Ansible Manager.

cd /opt
sudo mkdir ansible-manager
sudo chown itential:itential ansible-manager
cd ansible-manager
sudo mkdir conf data
sudo chown itential:itential conf data
sudo -u itential ansible-manager --generate-properties-file --properties-file=conf/properties.yml

Property Settings

Configurations for Itential Ansible Manager are stored in a yml file located at /opt/ansible-manager/conf/properties.yml

Property	Sample Value	Description
vault_password_file	/opt/ansible/.vault_password_file	The vault_password_file may be configured to point to a file containing the vault password. This file should be secured with 0400 permissions. This parameter is only needed if vault passwords are being used.
inventory_file	~/.ansible/hosts	The inventory_file may be configured to point to the location of an existing Ansible inventory file or script. If there is no existing Ansible inventory, you may omit this parameter and add devices directly to the Ansible Manager database.
role_path	/usr/share/ansible/roles	The role_path should be configured to point to a folder containing any Ansible roles that will be discovered by Itential Ansible Manager. It can be set to either a single path or a list of paths. A list of role paths has the format ['/path1', /path2', '/path3'].
playbook_path	/usr/share/ansible/playbooks	The playbook_path should be configured to point to a folder containing any Ansible playbooks that will be discovered by Itential Ansible Manager. It can be set to either a single path or a list of paths. A list of playbook paths has the format ['/path1', '/path2', '/path3'].
authentication_disabled	false	The authentication_disabled property should be set to false in shared network environments. You may choose to disable authentication if running in a virtual machine (VM) on your laptop.
authentication_max_sessions	5	The authentication_max_sessions property controls how many concurrent sessions are allowed for each user.
authentication_idle_timeout	600	The authentication_idle_timeout property controls the duration of the user session when no activity occurs.
data_file	sqlite:////opt/ansible-manager/data/ansible-manager.db	The data_file should be configured to point to a SQLite DB file. This DB file should be located on a persistent volume so it is not lost across server restarts. Note: When referencing an absolute path, four slash marks / must be present in the url.
strict_args	true	The strict_args parameter controls whether schema validation should be performed when invoking Ansible modules. This value should be set to true.
external_address	http://ansible-manager.example.com:8080	For use with an external proxy and for generating redirects.

Additional Requirements for Settings

• Configure the vault_password_file and inventory_file if an existing Ansible inventory will be used.
• Configure the role_path and playbook_path to point to your custom Ansible roles and playbooks.
• Configure the data_file to be located on your persistent volume.

Sample Properties.yml File

An example properties.yml file is shown below.

vi /opt/ansible-manager/conf/properties.yml

#
# Port to listen on
#
port: 8083

#
# Path to the ansible manager sqlite database file
# Be sure to place this file on a persistent volume.
#
data_file: 'sqlite:////opt/ansible-manager/data/ansible-manager.db'

#
# Path to the set of ansible roles you would like to invoke from the ansible manager.
# This can be set to either a single path or a list of paths.
#
# This is what a list of paths looks like:
# role_path: ['ansible_manager/integrations/roles', '/user/share/ansible/roles']
#
role_path: /usr/share/ansible/roles

#
# Path to the set of ansible playbooks you would like to invoke from the ansible manager.
# This can be set to either a single path or a list of paths.
#
# This is what a list of paths looks like:
# playbook_path: ['/usr/share/ansible/playbooks', '/usr/share/ansible/playbooks2']
#
playbook_path: /usr/share/ansible/playbooks

#
# Name of Ansible external inventory file.
# Uncomment this property if you will be using an existing ansible inventory
#
#inventory_file: ~/.ansible/hosts

#
# Name of file that contains password used by ansible-vault to encrypt strings.
# Uncomment this property if you will be using ansible vault encrypted variables
# Be sure to secure this file with permissions of 0200 or 0400
#
#vault_password_file: /opt/ansible-manager/conf/.vault_password_file

#
# Whether authentication is disabled or not
# Warning: only disable authentication on a personal vm environment
#
authentication_disabled: false

#
# The maximum number of concurrent sessions allowed.
#
authentication_max_sessions: 5000

#
# The idle timeout of each session (in seconds)
#
authentication_idle_timeout: 600

#
# The strict_args property controls whether schema validation will be performed when invoking
# ansible modules, roles, and playbooks.
# This property may be set to false for development and lab environments while modules,
# roles, and playbooks are being decorated.
# This property should be set to true for testing and production workloads.
#
strict_args: false

#
# Base of url for external proxy, used for generating redirects:
# external_address: 'http://ansible-manager.example.com:8080'

#
# Set the ansible_debug property to true to log additional debug messages when
# executing ansible modules, roles, or playbooks.
#
#ansible_debug: true

#
# Set the no_cleanup property to true to maintain temporary files created during the
# execution of ansible modules, roles, or playbooks.
#
#no_cleanup: true

Verify File Ownership

Verify the properties.yml file is owned by the Itential user.

sudo chown itential:itential /opt/ansible-manager/conf/properties.yml

Move Required Roles to the role_path Directory

There are several roles within the /usr/lib/python3.6/site-packages/ansible_manager/integrations/roles directory that must be copied to the roles directory configured within properties.yml (see the role_path property).

Note: These roles are required by Ansible Manager. If a role exists with this name already, it must be renamed.

sudo cp -R /usr/lib/python3.6/site-packages/ansible_manager/integrations/roles/* /usr/share/ansible/roles
sudo chown -R itential:itential /usr/share/ansible/roles

Start the Ansible Manager Server

Ansible Manager includes a script named ansible-manager that is located in /usr/bin/ansible-manager.

The script is used to start the Ansible Manager server and the path is within the $PATH variable.

$ sudo su itential -c ansible-manager
Ansible external inventory file: /opt/
Ansible Version: 2.7.1
Ansible device count: 112
Ansible group count: 1
Ansible modules path: /usr/lib/python2.7/site-packages/ansible/modules/network
Ansible modules metadata directory: ansible_manager/metadata/modules
Error reading YAML: /usr/lib/python2.7/site-packages/ansible/modules/network/netscaler/netscaler_lb_monitor.py
Error reading YAML: /usr/lib/python2.7/site-packages/ansible/modules/network/netscaler/netscaler_lb_vserver.py
Ansible module count: 669
Ansible roles path: /usr/share/ansible/roles
Ansible roles metadata directory: ansible_manager/metadata/roles
Ansible role count: 3
Ansible playbooks path: /usr/share/ansible/playbooks
Ansible playbooks metadata directory: ansible_manager/metadata/playbooks
Ansible playbook count: 16
 * Serving Flask app "telegraph" (lazy loading)
 * Environment: production
   WARNING: Do not use the development server in a production environment.
   Use a production WSGI server instead.
 * Debug mode: off
 * Running on http://0.0.0.0:8083/ (Press CTRL+C to quit)

Start Ansible Manager Server as a Systemd Service

To run Ansible Manager as a daemon, add the following systemd startup script to your system. If python is installed in a non-standard location, you may need to adjust the path to the python 3.6 executable.

sudo vi /etc/systemd/system/ansible-manager.service

[Unit]
Description=Itential Ansible Manager
After=network.target

[Service]
User=itential
Restart=always
Type=simple
ExecStart=/bin/ansible-manager
WorkingDirectory=/tmp
Environment=MAX_EVENT_RES=15000000

[Install]
WantedBy=multi-user.target

Reload systemd so that it is aware of the new service. Then start/stop/status Ansible Manager.

$ sudo systemctl daemon-reload
$ sudo systemctl start ansible-manager
$ sudo systemctl status ansible-manager
● ansible-manager.service - Itential Ansible Manager
   Loaded: loaded (/etc/systemd/system/ansible-manager.service; disabled; vendor preset: disabled)
   Active: active (running) since Wed 2018-11-07 21:06:43 UTC; 16s ago
 Main PID: 26353 (python3.6)
   CGroup: /system.slice/ansible-manager.service
           └─26353 /bin/python3.6 telegraph.pyc

Nov 07 21:06:56 telegraph01 python3.6[26353]: Ansible role count: 3
Nov 07 21:06:56 telegraph01 python3.6[26353]: Ansible playbooks path: /opt/ansible/playbooks
Nov 07 21:06:56 telegraph01 python3.6[26353]: Ansible playbooks metadata directory: ansible_manager/metadata/playbooks
Nov 07 21:06:56 telegraph01 python3.6[26353]: Ansible playbook count: 16
Nov 07 21:06:56 telegraph01 python3.6[26353]: * Serving Flask app "telegraph" (lazy loading)
Nov 07 21:06:56 telegraph01 python3.6[26353]: * Environment: production
Nov 07 21:06:56 telegraph01 python3.6[26353]: WARNING: Do not use the development server in a production environment.
Nov 07 21:06:56 telegraph01 python3.6[26353]: Use a production WSGI server instead.
Nov 07 21:06:56 telegraph01 python3.6[26353]: * Debug mode: off
Nov 07 21:06:56 telegraph01 python3.6[26353]: * Running on http://0.0.0.0:8083/ (Press CTRL+C to quit)

sudo systemctl stop ansible-manager

Note: Ansible Manager uses the Ansible Runner software package to exchange data to and from Ansible. Currently, Ansible Runner limits the size of the results data that can be returned from Ansible. You can increase this limit by setting the environment variable MAX_EVENT_RES. If the message "No results data available" is received while retrieving operational or configuration data from a device, perform the following steps to increase the MAX_EVENT_RES variable:

1. Edit the /etc/systemd/system/ansible-manager.service file.
2. Run sudo systemctl daemon-reload.
3. Restart the Ansible Manager.

Enable Ansible Manager Server to Start on System Boot (Optional)

As long as the previous step is completed and Ansible Manager has been setup as a systemd service properly, the following commands are used to enable Ansible Manager to start when the system boots.

$ sudo systemctl is-enabled ansible-manager
disabled
$ sudo systemctl enable ansible-manager
Created symlink from /etc/systemd/system/multi-user.target.wants/ansible-manager.service to /etc/systemd/system/ansible-manager.service.